.TH std::stack::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::stack::emplace \- std::stack::emplace

.SH Synopsis
   template< class... Args >                  \fI(since C++11)\fP
   void emplace( Args&&... args );            \fI(until C++17)\fP
   template< class... Args >                  \fI(since C++17)\fP
   decltype(auto) emplace( Args&&... args );

   Pushes a new element on top of the stack. The element is constructed in-place, i.e.
   no copy or move operations are performed. The constructor of the element is called
   with exactly the same arguments as supplied to the function.

   Effectively calls c.emplace_back(std::forward<Args>(args)...);.

.SH Parameters

   args - arguments to forward to the constructor of the element

.SH Return value

   \fI(none)\fP                                                                 \fI(until C++17)\fP
   The value or reference, if any, returned by the above call to          \fI(since C++17)\fP
   Container::emplace_back.

.SH Complexity

   Identical to the complexity of Container::emplace_back.

.SH Example


// Run this code

 #include <iostream>
 #include <stack>

 struct S
 {
     int id;

     S(int i, double d, std::string s) : id{i}
     {
         std::cout << "S::S(" << i << ", " << d << ", \\"" << s << "\\");\\n";
     }
 };

 int main()
 {
     std::stack<S> stack;
     const S& s = stack.emplace(42, 3.14, "C++"); // for return value C++17 required
     std::cout << "id = " << s.id << '\\n';
 }

.SH Output:

 S::S(42, 3.14, "C++")
 id = 42

  Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to           Behavior as published              Correct behavior
   LWG 2783 C++17      emplace returned reference, breaking      returns decltype(auto)
                       compatibility with pre-C++17 containers

.SH See also

   push inserts element at the top
        \fI(public member function)\fP
   pop  removes the top element
        \fI(public member function)\fP
